// filepath: /home/debi/IdeaProjects/LearnRust/Work/basic/src/stdx/ffix/cppx/bridge.h

/**
 * bridge.h - Rust 与 C++ FFI 桥接头文件
 * 
 * 本文件定义了 C++ 端需要实现的函数接口，以便 Rust 代码调用
 * 同时也声明了 Rust 提供给 C++ 调用的函数
 */

#ifndef RUST_CPP_BRIDGE_H
#define RUST_CPP_BRIDGE_H

#include <stdint.h>
#include <stddef.h>

#ifdef __cplusplus
extern "C" {
#endif

// ============================================================================
// C++ 端实现，供 Rust 调用
// ============================================================================

/**
 * C++ 加法函数
 * @param a 第一个加数
 * @param b 第二个加数
 * @return 两数之和
 */
int32_t cpp_add(int32_t a, int32_t b);

/**
 * C++ 字符串处理函数
 * @param input 输入的 C 字符串（以 null 结尾）
 * @return 处理后的新字符串（调用者需要使用 cpp_free_string 释放）
 */
char* cpp_process_string(const char* input);

/**
 * C++ 分配双精度浮点数组
 * @param size 数组大小
 * @return 指向分配的数组的指针（调用者需要使用 cpp_free_array 释放）
 */
double* cpp_allocate_array(int32_t size);

/**
 * C++ 释放数组内存
 * @param ptr 要释放的数组指针
 */
void cpp_free_array(double* ptr);

/**
 * C++ 计算函数
 * @param x 第一个参数
 * @param y 第二个参数
 * @return 计算结果：x * y + sqrt(x) + y^2
 */
double cpp_calculate(double x, double y);

/**
 * 复杂数据结构定义（C 兼容的内存布局）
 */
typedef struct {
    int32_t id;           // ID
    double value;         // 数值
    char name[64];        // 固定大小的名称字符数组
    uint32_t flags;       // 标志位
} ComplexData;

/**
 * C++ 处理复杂数据结构
 * @param data 指向复杂数据的指针
 * @return 处理结果状态码（0 表示成功）
 */
int32_t cpp_process_complex_data(const ComplexData* data);

/**
 * 回调函数类型定义
 */
typedef int32_t (*Callback)(int32_t);

/**
 * C++ 调用回调函数
 * @param callback 回调函数指针
 * @param value 传递给回调函数的值
 * @return 回调函数的返回值
 */
int32_t cpp_call_with_callback(Callback callback, int32_t value);

// ============================================================================
// Rust 端实现，供 C++ 调用
// ============================================================================

/**
 * Rust 乘法函数
 * @param a 第一个乘数
 * @param b 第二个乘数
 * @return 两数之积
 */
int32_t rust_multiply(int32_t a, int32_t b);

/**
 * Rust 字符串连接函数
 * @param s1 第一个字符串
 * @param s2 第二个字符串
 * @return 连接后的新字符串（调用者需要使用 rust_free_string 释放）
 */
char* rust_concat_strings(const char* s1, const char* s2);

/**
 * Rust 释放字符串内存
 * @param s 要释放的字符串指针
 */
void rust_free_string(char* s);

/**
 * Rust 数组求和函数
 * @param arr 数组指针
 * @param len 数组长度
 * @return 数组元素的总和
 */
double rust_sum_array(const double* arr, int32_t len);

/**
 * Rust 回调函数：将输入值翻倍
 * @param x 输入值
 * @return 输入值的两倍
 */
int32_t rust_callback_double(int32_t x);

/**
 * Rust 回调函数：返回输入值的平方
 * @param x 输入值
 * @return 输入值的平方
 */
int32_t rust_callback_square(int32_t x);

/**
 * Rust 创建线程安全的共享数据对象
 * @return 不透明指针，指向 SharedData 对象
 */
void* rust_create_shared_data(void);

/**
 * 向 Rust SharedData 对象添加值
 * @param ptr SharedData 对象指针
 * @param value 要添加的值
 */
void rust_shared_data_add(void* ptr, int32_t value);

/**
 * 获取 Rust SharedData 对象中所有值的总和
 * @param ptr SharedData 对象指针
 * @return 总和
 */
int32_t rust_shared_data_get_sum(void* ptr);

/**
 * 释放 Rust SharedData 对象
 * @param ptr SharedData 对象指针
 */
void rust_free_shared_data(void* ptr);

/**
 * 错误码枚举
 */
typedef enum {
    ErrorCode_Success = 0,
    ErrorCode_NullPointer = 1,
    ErrorCode_InvalidArgument = 2,
    ErrorCode_OutOfMemory = 3,
    ErrorCode_UnknownError = 99
} ErrorCode;

/**
 * Rust 安全除法函数（带错误处理）
 * @param a 被除数
 * @param b 除数
 * @param result 结果输出指针
 * @return 错误码
 */
ErrorCode rust_safe_divide(double a, double b, double* result);

#ifdef __cplusplus
}
#endif

// ============================================================================
// C++ 专用接口（使用 C++ 特性）
// ============================================================================

#ifdef __cplusplus

#include <string>
#include <vector>

namespace rust_cpp_bridge {

/**
 * Point 结构体（用于 cxx 库）
 */
struct Point {
    double x;
    double y;
    
    Point(double x = 0.0, double y = 0.0) : x(x), y(y) {}
};

/**
 * Person 结构体（用于 cxx 库）
 */
struct Person {
    std::string name;
    int32_t age;
    
    Person(const std::string& name = "", int32_t age = 0) 
        : name(name), age(age) {}
};

/**
 * CppVector 类（示例 C++ 类的封装）
 */
class CppVector {
private:
    std::vector<int32_t> data;
    
public:
    CppVector() = default;
    
    void push_value(int32_t value) {
        data.push_back(value);
    }
    
    int32_t get_sum() const {
        int32_t sum = 0;
        for (int32_t v : data) {
            sum += v;
        }
        return sum;
    }
    
    size_t size() const {
        return data.size();
    }
};

/**
 * 计算两点之间的距离
 */
double calculate_distance(const Point& p1, const Point& p2);

/**
 * 创建问候语
 */
std::string create_greeting(const Person& person);

/**
 * 创建 CppVector 对象
 */
CppVector* create_cpp_vector();

} // namespace rust_cpp_bridge

#endif // __cplusplus

// ============================================================================
// 使用说明与注意事项
// ============================================================================

/*
编译说明：

1. 编译 C++ 代码为动态库：
   g++ -shared -fPIC -o libbridge.so bridge.cpp -std=c++14

2. 在 build.rs 中链接：
   println!("cargo:rustc-link-search=native=/path/to/lib");
   println!("cargo:rustc-link-lib=dylib=bridge");

3. 或者使用 cc crate（在 build.rs 中）：
   cc::Build::new()
       .cpp(true)
       .file("src/bridge.cpp")
       .flag("-std=c++14")
       .compile("bridge");

注意事项：

1. **ABI 兼容性**：
   - 使用 extern "C" 避免 C++ 名称修饰
   - 跨 FFI 边界只传递 C 兼容的类型
   - 避免传递 C++ 特有类型（如 std::string, std::vector）

2. **内存管理**：
   - 谁分配谁释放的原则
   - 从 Rust 分配的内存由 Rust 释放
   - 从 C++ 分配的内存由 C++ 释放

3. **字符串处理**：
   - 使用 null 结尾的 C 字符串
   - 注意编码问题（UTF-8）
   - 记得释放分配的字符串内存

4. **异常安全**：
   - C++ 异常不能跨 FFI 边界
   - 在 C++ 端捕获所有异常
   - 使用错误码或其他机制报告错误

5. **线程安全**：
   - 确保跨 FFI 边界的数据结构是线程安全的
   - 使用适当的同步机制

示例用法（C++ 端）：

```cpp
#include "bridge.h"
#include <iostream>

int main() {
    // 调用 Rust 函数
    int result = rust_multiply(6, 7);
    std::cout << "Rust multiply: 6 * 7 = " << result << std::endl;
    
    // 使用 Rust 的字符串函数
    const char* s1 = "Hello ";
    const char* s2 = "from C++";
    char* concatenated = rust_concat_strings(s1, s2);
    if (concatenated) {
        std::cout << "Concatenated: " << concatenated << std::endl;
        rust_free_string(concatenated);
    }
    
    // 使用 Rust 的数组求和
    double numbers[] = {1.0, 2.0, 3.0, 4.0, 5.0};
    double sum = rust_sum_array(numbers, 5);
    std::cout << "Array sum: " << sum << std::endl;
    
    return 0;
}
```

示例用法（Rust 端）：

```rust
use std::ffi::CString;

fn main() {
    unsafe {
        // 调用 C++ 函数
        let result = cpp_add(10, 20);
        println!("C++ add: 10 + 20 = {}", result);
        
        // 使用 C++ 的字符串处理
        let input = CString::new("Hello from Rust").unwrap();
        let output_ptr = cpp_process_string(input.as_ptr());
        if !output_ptr.is_null() {
            let output = CStr::from_ptr(output_ptr).to_string_lossy();
            println!("Processed: {}", output);
            // 注意：需要调用 C++ 的释放函数
        }
    }
}
```
*/

#endif // RUST_CPP_BRIDGE_H

